diff --git a/README.md b/README.md index f075261..d0d4401 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ -# Maestro Bitcoin Go SDK +# Maestro Bitcoin Go SDK API Library Go Reference -The Maestro Bitcoin Go SDK provides convenient access to [the Maestro Bitcoin REST +The Maestro Bitcoin Go SDK library provides convenient access to [the Maestro REST + API](https://docs.gomaestro.org/) from applications written in Go. The full API of this library can be found in [api.md](api.md). ## Installation @@ -49,13 +50,17 @@ import ( func main() { client := maestrobitcoingosdk.NewClient( option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("API_KEY") - option.WithEnvironmentMainnet(), // defaults to option.WithEnvironmentMainnet() + option.WithEnvironmentMainnet(), // or option.WithEnvironmentTestnet() | option.WithEnvironmentDefault(); defaults to option.WithEnvironmentTestnet() + ) + paginatedUtxo, err := client.Addresses.Utxos.List( + context.TODO(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, ) - timestampedBlock, err := client.Blocks.Latest.Get(context.TODO()) if err != nil { panic(err.Error()) } - fmt.Printf("%+v\n", timestampedBlock.Data) + fmt.Printf("%+v\n", paginatedUtxo.Data) } ``` @@ -144,7 +149,7 @@ client := maestrobitcoingosdk.NewClient( option.WithHeader("X-Some-Header", "custom_header_info"), ) -client.Blocks.Latest.Get(context.TODO(), ..., +client.Addresses.Utxos.List(context.TODO(), ..., // Override the header option.WithHeader("X-Some-Header", "some_other_custom_header_info"), // Add an undocumented field to the request body, using sjson syntax @@ -173,14 +178,18 @@ When the API returns a non-success status code, we return an error with type To handle errors, we recommend that you use the `errors.As` pattern: ```go -_, err := client.Blocks.Latest.Get(context.TODO()) +_, err := client.Addresses.Utxos.List( + context.TODO(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, +) if err != nil { var apierr *maestrobitcoingosdk.Error if errors.As(err, &apierr) { println(string(apierr.DumpRequest(true))) // Prints the serialized HTTP request println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response } - panic(err.Error()) // GET "/blocks/latest": 400 Bad Request { ... } + panic(err.Error()) // GET "/addresses/{address}/utxos": 400 Bad Request { ... } } ``` @@ -198,8 +207,10 @@ To set a per-retry timeout, use `option.WithRequestTimeout()`. // This sets the timeout for the request, including all the retries. ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) defer cancel() -client.Blocks.Latest.Get( +client.Addresses.Utxos.List( ctx, + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, // This sets the per-retry timeout option.WithRequestTimeout(20*time.Second), ) @@ -233,7 +244,12 @@ client := maestrobitcoingosdk.NewClient( ) // Override per-request: -client.Blocks.Latest.Get(context.TODO(), option.WithMaxRetries(5)) +client.Addresses.Utxos.List( + context.TODO(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + option.WithMaxRetries(5), +) ``` ### Making custom/undocumented requests diff --git a/address.go b/address.go index 8eb1bf7..867fc0c 100644 --- a/address.go +++ b/address.go @@ -7,7 +7,7 @@ import ( ) // AddressService contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/addressbrc20.go b/addressbrc20.go index fd3a75d..1aea71c 100644 --- a/addressbrc20.go +++ b/addressbrc20.go @@ -14,7 +14,7 @@ import ( ) // AddressBrc20Service contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/addressrune.go b/addressrune.go index db7d38e..4d69879 100644 --- a/addressrune.go +++ b/addressrune.go @@ -17,7 +17,7 @@ import ( ) // AddressRuneService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/addresstx.go b/addresstx.go index 9aa3816..43f2be6 100644 --- a/addresstx.go +++ b/addresstx.go @@ -17,7 +17,7 @@ import ( ) // AddressTxService contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/addressutxo.go b/addressutxo.go index e35a216..f6be1ac 100644 --- a/addressutxo.go +++ b/addressutxo.go @@ -17,7 +17,7 @@ import ( ) // AddressUtxoService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/asset.go b/asset.go index 5cb61cd..986e3da 100644 --- a/asset.go +++ b/asset.go @@ -7,7 +7,7 @@ import ( ) // AssetService contains methods and other services that help with interacting with -// the maestro API. +// the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/assetbrc20.go b/assetbrc20.go index 3e50fe4..fcb3b45 100644 --- a/assetbrc20.go +++ b/assetbrc20.go @@ -17,7 +17,7 @@ import ( ) // AssetBrc20Service contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/assetbrc20holder.go b/assetbrc20holder.go index 06acbcd..7d985a4 100644 --- a/assetbrc20holder.go +++ b/assetbrc20holder.go @@ -17,7 +17,7 @@ import ( ) // AssetBrc20HolderService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/assetrune.go b/assetrune.go index ae7ed98..2937519 100644 --- a/assetrune.go +++ b/assetrune.go @@ -17,7 +17,7 @@ import ( ) // AssetRuneService contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/assetruneholder.go b/assetruneholder.go index b243da2..efff0a8 100644 --- a/assetruneholder.go +++ b/assetruneholder.go @@ -17,7 +17,7 @@ import ( ) // AssetRuneHolderService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/assetruneutxo.go b/assetruneutxo.go index d35a590..4162bb7 100644 --- a/assetruneutxo.go +++ b/assetruneutxo.go @@ -17,7 +17,7 @@ import ( ) // AssetRuneUtxoService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/block.go b/block.go index 76567fb..e048274 100644 --- a/block.go +++ b/block.go @@ -15,7 +15,7 @@ import ( ) // BlockService contains methods and other services that help with interacting with -// the maestro API. +// the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/blocklatest.go b/blocklatest.go index 9edeac2..13ccbfc 100644 --- a/blocklatest.go +++ b/blocklatest.go @@ -11,7 +11,7 @@ import ( ) // BlockLatestService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/client.go b/client.go index cd126a3..a92972c 100644 --- a/client.go +++ b/client.go @@ -12,7 +12,7 @@ import ( ) // Client creates a struct with services and top level methods that help with -// interacting with the maestro API. You should not instantiate this client +// interacting with the Maestro API. You should not instantiate this client // directly, and instead use the [NewClient] method instead. type Client struct { Options []option.RequestOption @@ -30,7 +30,7 @@ type Client struct { // default arguments, and all option will be passed down to the services and // requests that this client makes. func NewClient(opts ...option.RequestOption) (r *Client) { - defaults := []option.RequestOption{option.WithEnvironmentMainnet()} + defaults := []option.RequestOption{option.WithEnvironmentTestnet()} if o, ok := os.LookupEnv("API_KEY"); ok { defaults = append(defaults, option.WithAPIKey(o)) } diff --git a/client_test.go b/client_test.go index d9129c5..05da746 100644 --- a/client_test.go +++ b/client_test.go @@ -37,7 +37,11 @@ func TestUserAgentHeader(t *testing.T) { }, }), ) - client.Blocks.Latest.Get(context.Background()) + client.Addresses.Utxos.List( + context.Background(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if userAgent != fmt.Sprintf("Maestro/Go %s", internal.PackageVersion) { t.Errorf("Expected User-Agent to be correct, but got: %#v", userAgent) } @@ -60,7 +64,11 @@ func TestRetryAfter(t *testing.T) { }, }), ) - res, err := client.Blocks.Latest.Get(context.Background()) + res, err := client.Addresses.Utxos.List( + context.Background(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("Expected there to be a cancel error and for the response to be nil") } @@ -94,7 +102,11 @@ func TestDeleteRetryCountHeader(t *testing.T) { }), option.WithHeaderDel("X-Stainless-Retry-Count"), ) - res, err := client.Blocks.Latest.Get(context.Background()) + res, err := client.Addresses.Utxos.List( + context.Background(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("Expected there to be a cancel error and for the response to be nil") } @@ -123,7 +135,11 @@ func TestOverwriteRetryCountHeader(t *testing.T) { }), option.WithHeader("X-Stainless-Retry-Count", "42"), ) - res, err := client.Blocks.Latest.Get(context.Background()) + res, err := client.Addresses.Utxos.List( + context.Background(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("Expected there to be a cancel error and for the response to be nil") } @@ -151,7 +167,11 @@ func TestRetryAfterMs(t *testing.T) { }, }), ) - res, err := client.Blocks.Latest.Get(context.Background()) + res, err := client.Addresses.Utxos.List( + context.Background(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("Expected there to be a cancel error and for the response to be nil") } @@ -173,7 +193,11 @@ func TestContextCancel(t *testing.T) { ) cancelCtx, cancel := context.WithCancel(context.Background()) cancel() - res, err := client.Blocks.Latest.Get(cancelCtx) + res, err := client.Addresses.Utxos.List( + cancelCtx, + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("Expected there to be a cancel error and for the response to be nil") } @@ -192,7 +216,11 @@ func TestContextCancelDelay(t *testing.T) { ) cancelCtx, cancel := context.WithTimeout(context.Background(), 2*time.Millisecond) defer cancel() - res, err := client.Blocks.Latest.Get(cancelCtx) + res, err := client.Addresses.Utxos.List( + cancelCtx, + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("expected there to be a cancel error and for the response to be nil") } @@ -217,7 +245,11 @@ func TestContextDeadline(t *testing.T) { }, }), ) - res, err := client.Blocks.Latest.Get(deadlineCtx) + res, err := client.Addresses.Utxos.List( + deadlineCtx, + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err == nil || res != nil { t.Error("expected there to be a deadline error and for the response to be nil") } diff --git a/general.go b/general.go index a431640..4d6c6a8 100644 --- a/general.go +++ b/general.go @@ -7,7 +7,7 @@ import ( ) // GeneralService contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/generalinfo.go b/generalinfo.go index 683006c..57447b7 100644 --- a/generalinfo.go +++ b/generalinfo.go @@ -12,7 +12,7 @@ import ( ) // GeneralInfoService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/option/requestoption.go b/option/requestoption.go index 7c2dafa..4135423 100644 --- a/option/requestoption.go +++ b/option/requestoption.go @@ -15,7 +15,7 @@ import ( "github.com/tidwall/sjson" ) -// RequestOption is an option for the requests made by the maestro API Client +// RequestOption is an option for the requests made by the Maestro API Client // which can be supplied to clients, services, and methods. You can read more about this functional // options pattern in our [README]. // @@ -221,6 +221,13 @@ func WithRequestTimeout(dur time.Duration) RequestOption { } } +// WithEnvironmentTestnet returns a RequestOption that sets the current +// environment to be the "testnet" environment. An environment specifies which base URL +// to use by default. +func WithEnvironmentTestnet() RequestOption { + return WithBaseURL("https://xbt-testnet.gomaestro-api.org/v0/") +} + // WithEnvironmentMainnet returns a RequestOption that sets the current // environment to be the "mainnet" environment. An environment specifies which base URL // to use by default. @@ -228,11 +235,11 @@ func WithEnvironmentMainnet() RequestOption { return WithBaseURL("https://xbt-mainnet.gomaestro-api.org/v0/") } -// WithEnvironmentTestnet returns a RequestOption that sets the current -// environment to be the "testnet" environment. An environment specifies which base URL +// WithEnvironmentDefault returns a RequestOption that sets the current +// environment to be the "default" environment. An environment specifies which base URL // to use by default. -func WithEnvironmentTestnet() RequestOption { - return WithBaseURL("https://xbt-testnet.gomaestro-api.org/v0/") +func WithEnvironmentDefault() RequestOption { + return WithBaseURL("mainnet/") } // WithAPIKey returns a RequestOption that sets the client setting "api_key". diff --git a/rpc.go b/rpc.go index 19c31da..4d367c1 100644 --- a/rpc.go +++ b/rpc.go @@ -7,7 +7,7 @@ import ( ) // RpcService contains methods and other services that help with interacting with -// the maestro API. +// the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpcmempool.go b/rpcmempool.go index cf86056..444830a 100644 --- a/rpcmempool.go +++ b/rpcmempool.go @@ -7,7 +7,7 @@ import ( ) // RpcMempoolService contains methods and other services that help with interacting -// with the maestro API. +// with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpcmempoolinfo.go b/rpcmempoolinfo.go index 447e5d7..2ea49f7 100644 --- a/rpcmempoolinfo.go +++ b/rpcmempoolinfo.go @@ -12,7 +12,7 @@ import ( ) // RpcMempoolInfoService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpcmempooltransaction.go b/rpcmempooltransaction.go index 49593bf..f027e43 100644 --- a/rpcmempooltransaction.go +++ b/rpcmempooltransaction.go @@ -14,7 +14,7 @@ import ( ) // RpcMempoolTransactionService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpcmempooltransactionancestor.go b/rpcmempooltransactionancestor.go index 0522f68..211345c 100644 --- a/rpcmempooltransactionancestor.go +++ b/rpcmempooltransactionancestor.go @@ -14,7 +14,7 @@ import ( ) // RpcMempoolTransactionAncestorService contains methods and other services that -// help with interacting with the maestro API. +// help with interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpcmempooltransactiondescendant.go b/rpcmempooltransactiondescendant.go index 89a392f..2005a4d 100644 --- a/rpcmempooltransactiondescendant.go +++ b/rpcmempooltransactiondescendant.go @@ -14,7 +14,7 @@ import ( ) // RpcMempoolTransactionDescendantService contains methods and other services that -// help with interacting with the maestro API. +// help with interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/rpctransaction.go b/rpctransaction.go index 1d629c6..52708da 100644 --- a/rpctransaction.go +++ b/rpctransaction.go @@ -14,7 +14,7 @@ import ( ) // RpcTransactionService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/transaction.go b/transaction.go index 386499b..2beb92b 100644 --- a/transaction.go +++ b/transaction.go @@ -14,7 +14,7 @@ import ( ) // TransactionService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/transactionpsbt.go b/transactionpsbt.go index 1494bbf..54742fa 100644 --- a/transactionpsbt.go +++ b/transactionpsbt.go @@ -12,7 +12,7 @@ import ( ) // TransactionPsbtService contains methods and other services that help with -// interacting with the maestro API. +// interacting with the Maestro API. // // Note, unlike clients, this service does not read variables from the environment // automatically. You should not instantiate this service directly, and instead use diff --git a/usage_test.go b/usage_test.go index c24ee39..9d3ccc9 100644 --- a/usage_test.go +++ b/usage_test.go @@ -24,9 +24,13 @@ func TestUsage(t *testing.T) { option.WithBaseURL(baseURL), option.WithAPIKey("My API Key"), ) - timestampedBlock, err := client.Blocks.Latest.Get(context.TODO()) + paginatedUtxo, err := client.Addresses.Utxos.List( + context.TODO(), + "REPLACE_ME", + maestrobitcoingosdk.AddressUtxoListParams{}, + ) if err != nil { t.Error(err) } - t.Logf("%+v\n", timestampedBlock.Data) + t.Logf("%+v\n", paginatedUtxo.Data) }